add type annotations to `Simulation` class #1919

oskooi · 2022-01-28T08:23:02Z

Even though Python is a dynamically typed language, type annotations (or hints) can be used for static analysis using tools such as mypy or pytype. It would be useful to eventually add type annotations to all Python classes and functions in the API. This way, we could add a static analyzer (including a linter) as a GitHub Action as part of the CI.

One anomaly with the current setup is that using the automated script generate_api_doc.py to update the user manual markdown page Python_User_Interface.md which is generated from the docstrings shows the module filename as part of the class name. For example, the Simulation constructor includes:

             boundary_layers: List[PML] = None,
             symmetries: List[Symmetry] = None,

which appears in the user manual as:

             boundary_layers: List[meep.simulation.PML] = None,
             symmetries: List[meep.simulation.Symmetry] = None,

It would be cleaner if the module filename meep.simulation did not appear. EDIT: Actually, this can be fixed by adding:

from __future__ import annotations

doc/docs/Python_User_Interface.md

stevengj · 2022-01-29T13:17:40Z

As a general principle, this seems fine, but one has to be very carefully about overly restricting the types, because then you lose flexibility — Python potentially has a wide variety of types that can, for example, represent a real number (and which are convertible by SWIG to double when we call the C++ API).

stevengj · 2022-01-29T13:19:09Z

Note also that this requires Python 3.5; what's the minimum version of Python that we currently support?

oskooi · 2022-01-29T18:36:34Z

Note also that this requires Python 3.5; what's the minimum version of Python that we currently support?

The GitHub actions CI uses Python 3.6 and 3.9. The Conda packages for the latest version 1.22 use Python 3.7 - 3.10.

Python 3.5 was released in September 2015 which is fairly outdated.

codecov-commenter · 2022-01-29T18:49:04Z

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 73.16%. Comparing base (4f2b0a4) to head (75758d9).
Report is 295 commits behind head on master.

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1919      +/-   ##
==========================================
+ Coverage   73.15%   73.16%   +0.01%     
==========================================
  Files          17       17              
  Lines        4924     4926       +2     
==========================================
+ Hits         3602     3604       +2     
  Misses       1322     1322

Files with missing lines	Coverage Δ
python/simulation.py	`76.87% <100.00%> (+0.01%)`	⬆️

doc/docs/Python_User_Interface.md

python/simulation.py

…markdown docs

stevengj · 2022-02-04T01:23:58Z

So int is a subtype of float in this type system?

oskooi · 2022-02-04T02:30:19Z

So int is a subtype of float in this type system?

Yes, that seems to be the case ever since PEP 484 which contains the typing module was introduced as part of the Python 3.5 release in September 2015.

stevengj · 2022-02-11T17:43:11Z

Is there a way to work with earlier Python releases? Requiring Python 3.7 for this is a bit annoying, since that is less than 4 years old. I don't mind requiring Python 3.5.

oskooi added 2 commits January 28, 2022 06:01

add type hints to constructor arguments of Simulation class

03443d7

specify default None for cell_size and resolution

6c86d5d

oskooi added the enhancement label Jan 28, 2022

stevengj reviewed Jan 29, 2022

View reviewed changes

doc/docs/Python_User_Interface.md Outdated Show resolved Hide resolved

stevengj reviewed Jan 29, 2022

View reviewed changes

doc/docs/Python_User_Interface.md Show resolved Hide resolved

use Optional type for certain members with None defaults and other fixes

7c697f6

oskooi changed the title ~~add type hints to constructor arguments of Simulation class~~ add type annotations to Simulation class Jan 29, 2022

oskooi changed the title ~~add type annotations to Simulation class~~ add type annotations to Simulation class Jan 29, 2022